From 2f544655f99361ebe1fee30f5c10ce3212461fea Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Wed, 16 Dec 2015 10:55:52 -0500
Subject: [PATCH] Revise CSS node documentation

Clarify the use of brackets in the CSS node diagrams:
[] means optional nodes or classes, <> means child widgets.
---
 gtk/gtkcheckbutton.c   |  6 ++++--
 gtk/gtkcheckmenuitem.c |  4 ++--
 gtk/gtkexpander.c      |  4 ++--
 gtk/gtkflowbox.c       |  4 ++--
 gtk/gtkgrid.c          |  2 +-
 gtk/gtklevelbar.c      |  4 ++--
 gtk/gtkmenu.c          |  4 +++-
 gtk/gtkmenuitem.c      |  2 +-
 gtk/gtkmodelbutton.c   |  6 +++---
 gtk/gtknotebook.c      | 13 +++++++------
 gtk/gtkpaned.c         |  4 +++-
 gtk/gtkradiobutton.c   |  6 ++++--
 gtk/gtkradiomenuitem.c |  4 ++--
 gtk/gtkscale.c         | 10 +++++-----
 gtk/gtktreeview.c      |  6 +++---
 gtk/gtkwindow.c        |  3 ++-
 16 files changed, 46 insertions(+), 36 deletions(-)

diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index 932469e48a..471543aa59 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -57,7 +57,8 @@
  *
  * |[<!-- language="plain" -->
  * checkbutton
- * ╰── check
+ * ├── check
+ * ╰── <child>
  * ]|
  *
  * A GtkCheckButton with indicator (see gtk_toggle_button_set_mode()) has a
@@ -65,7 +66,8 @@
  *
  * |[<!-- language="plain" -->
  * button.check
- * ╰── [check]
+ * ├── check
+ * ╰── <child>
  * ]|
  *
  * A GtkCheckButton without indicator changes the name of its main node
diff --git a/gtk/gtkcheckmenuitem.c b/gtk/gtkcheckmenuitem.c
index d8654a9d8e..aaf830402b 100644
--- a/gtk/gtkcheckmenuitem.c
+++ b/gtk/gtkcheckmenuitem.c
@@ -53,8 +53,8 @@
  *
  * |[<!-- language="plain" -->
  * menuitem
- * ├── ...
- * ╰── check.right
+ * ├── check.left
+ * ╰── <child>
  * ]|
  *
  * GtkCheckMenuItem has a main CSS node with name menuitem, and a subnode
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index 0c32ff2a08..e3d3291e94 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -94,8 +94,8 @@
  * expander
  * ├── title
  * │   ├── arrow
- * │   ╰── label widget
- * ╰── child
+ * │   ╰── <label widget>
+ * ╰── <child>
  * ]|
  *
  * GtkExpander has three CSS nodes, the main node with the name expander,
diff --git a/gtk/gtkflowbox.c b/gtk/gtkflowbox.c
index 018804dd74..358321976e 100644
--- a/gtk/gtkflowbox.c
+++ b/gtk/gtkflowbox.c
@@ -57,9 +57,9 @@
  * |[<!-- language="plain" -->
  * flowbox
  * ├── flowboxchild
- * │   ╰── child
+ * │   ╰── <child>
  * ├── flowboxchild
- * │   ╰── child
+ * │   ╰── <child>
  * ┊
  * ╰── [rubberband]
  * ]|
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index 50edea7ce8..5fed33fe2d 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -55,7 +55,7 @@
  *
  * # CSS nodes
  *
- * GtkGrid uses a single CSS node wiht name grid.
+ * GtkGrid uses a single CSS node with name grid.
  */
 
 typedef struct _GtkGridChild GtkGridChild;
diff --git a/gtk/gtklevelbar.c b/gtk/gtklevelbar.c
index 2477d12ba6..45d9d4a0c6 100644
--- a/gtk/gtklevelbar.c
+++ b/gtk/gtklevelbar.c
@@ -89,7 +89,7 @@
  * |[<!-- language="plain" -->
  * levelbar[.discrete]
  * ╰── trough
- *     ├── block.filled.<level-name>
+ *     ├── block.filled.level-name
  *     ┊
  *     ├── block.empty
  *     ┊
@@ -100,7 +100,7 @@
  * trough node are a number of nodes with name block and style class .filled
  * or .empty. In continuous mode, there is exactly one node of each, in discrete
  * mode, the number of filled and unfilled nodes corresponds to blocks that are
- * drawn. The block.filled nodes also get a style class .<level-name> corresponding
+ * drawn. The block.filled nodes also get a style class .level-name corresponding
  * to the level for the current value.
  */
 #include "config.h"
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 78ff677744..fa7eda752d 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -88,7 +88,9 @@
  * |[<!-- language="plain" -->
  * menu
  * ├── arrow.top
- * ├── ...
+ * ├── <child>
+ * ┊
+ * ├── <child>
  * ╰── arrow.bottom
  * ]|
  *
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 252b93ca8d..c29c30c12c 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -92,7 +92,7 @@
  *
  * |[<!-- language="plain" -->
  * menuitem
- * ├── ...
+ * ├── <child>
  * ╰── [arrow.right]
  * ]|
  *
diff --git a/gtk/gtkmodelbutton.c b/gtk/gtkmodelbutton.c
index 0cbdbbe76a..727ea67f6c 100644
--- a/gtk/gtkmodelbutton.c
+++ b/gtk/gtkmodelbutton.c
@@ -111,19 +111,19 @@
  *
  * |[<!-- language="plain" -->
  * modelbutton
- * ├── ...
+ * ├── <child>
  * ╰── check
  * ]|
  *
  * |[<!-- language="plain" -->
  * modelbutton
- * ├── ...
+ * ├── <child>
  * ╰── radio
  * ]|
  *
  * |[<!-- language="plain" -->
  * modelbutton
- * ├── ...
+ * ├── <child>
  * ╰── arrow
  * ]|
  *
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 6dddcb8f1e..5d27c6c4a1 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -101,19 +101,20 @@
  * |[<!-- language="plain" -->
  * notebook
  * ├── header.top
- * │   ├── [action widget]
+ * │   ├── [<action widget>]
  * │   ├── tabs
  * │   │   ├── [arrow]
  * │   │   ├── tab
- * ┊   ┊   ┊   ╰── [tab label]
+ * │   │   │   ╰── <tab label>
+ * ┊   ┊   ┊
  * │   │   ├── tab[.reorderable-page]
- * │   │   │   ╰── [tab label]
+ * │   │   │   ╰── <tab label>
  * │   │   ╰── [arrow]
- * │   ╰── [action widget]
+ * │   ╰── [<action widget>]
  * │
- * ├── [child]
+ * ├── <child>
  * ┊
- * ╰── [child]
+ * ╰── <child>
  * ]|
  *
  * GtkNotebook has a main CSS node with name notebook, a subnode
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index 531f5f0c70..dfab414f1d 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -85,7 +85,9 @@
  *
  * |[<!-- language="plain" -->
  * paned
- * ╰── separator[.wide]
+ * ├── <child>
+ * ├── separator[.wide]
+ * ╰── <child>
  * ]|
  *
  * GtkPaned has a main CSS node with name paned, and a subnode for
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index 53191a48cf..59ca75cf91 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -76,7 +76,8 @@
  *
  * |[<!-- language="plain" -->
  * radiobutton
- * ╰── radio
+ * ├── radio
+ * ╰── <child>
  * ]|
  *
  * A GtkRadioButton with indicator (see gtk_toggle_button_set_mode()) has a
@@ -84,7 +85,8 @@
  *
  * |[<!-- language="plain" -->
  * button.radio
- * ╰── [radio]
+ * ├── radio
+ * ╰── <child>
  * ]|
  *
  * A GtkRadioButton without indicator changes the name of its main node
diff --git a/gtk/gtkradiomenuitem.c b/gtk/gtkradiomenuitem.c
index 919b8473f8..ee70dd70ca 100644
--- a/gtk/gtkradiomenuitem.c
+++ b/gtk/gtkradiomenuitem.c
@@ -66,8 +66,8 @@
  *
  * |[<!-- language="plain" -->
  * menuitem
- * ├── ...
- * ╰── radio
+ * ├── radio.left
+ * ╰── <child>
  * ]|
  *
  * GtkRadioMenuItem has a main CSS node with name menuitem, and a subnode
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 07a7a61efe..364b27f4c2 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -78,16 +78,16 @@
  * scale[.fine-tune]
  * ├── marks.top
  * │   ├── mark
- * │   ├── mark
- * │   ╰── ...
+ * ┊   ┊
+ * │   ╰── mark
  * ├── trough
- * │   ├──slider
+ * │   ├── slider
  * │   ├── [highlight]
  * │   ╰── [fill]
  * ╰── marks.bottom
  *     ├── mark
- *     ├── mark
- *     ╰── ...
+ *     ┊
+ *     ╰── mark
  * ]|
  *
  * GtkScale has a main CSS node with name scale, and subnodes with names
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 06924eb818..7e2f0277a9 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -129,9 +129,9 @@
  * |[<!-- language="plain" -->
  * treeview.view
  * ├── header
- * │   ├── [column header]
- * │   ├── [column header]
-   ┊   ┊
+ * │   ├── <column header>
+ * ┊   ┊
+ * │   ╰── <column header>
  * │
  * ╰── [rubberband]
  * ]|
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 3580daf653..802904c8d0 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -131,7 +131,8 @@
  *
  * |[<!-- language="plain" -->
  * window
- * ╰── decoration
+ * ├── decoration
+ * ╰── <child>
  * ]|
  *
  * GtkWindow has a main CSS node with name window and style class .background,
-- 
2.30.2